home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 5: The Fifth Dimension / 17 Bit - The Fifth Dimension (1995)(17 Bit Software)[!].iso / files / 3495.dms / 3495.adf / ProNET / autodoc / pronet.doc
Text File  |  1992-09-02  |  6KB  |  181 lines
  1. TABLE OF CONTENTS
  2.  
  3. pronet.device/--Overview--
  4. pronet.device/OpenDevice
  5. pronet.device/CMD_WRITE
  6. pronet.device/ReceivedData
  7. pronet.device/GetConfigString
  8. pronet.device/FreeConfigString
  9.  
  10. pronet.device/--Overview--                         pronet.device/--Overview--
  11.  
  12. ProNET.device  is able to connect two machines for transfering data between
  13. them.   For  the  transfer,  you must select a so-called PORT number, which
  14. must  be  specified  at  device  opening time, and when sending data to the
  15. corresponding port at the other machine, only the application that has this
  16. number will receive the data.  If the destination port doesn't exist on the
  17. other  Amiga,  the  data  will be buffered and will be sent at once when an
  18. application opens this port.
  19.  
  20.   This  device  differs  from  most  other devices in so far as the command
  21. CMD_READ  is  not recognized at all.  Instead, every chunk of data arriving
  22. at  your  port  will be sent to a MessagePort you also specified at opening
  23. time,  no  matter if you want it or not.  This message must be ReplyMsg()ed
  24. after evaluating the data.
  25.  
  26.   The  configuration of the device and applications using it is done by the
  27. file DEVS:ProNET.config.  It is built as follows:
  28.     title data    or
  29.     ; Comment
  30. 'title'  is  a string normally ending with a colon (':'), and 'data' may be
  31. any string which can be got using the #?ConfigString-Functions.
  32.  
  33.   An  important  line  in  DEVS:ProNET.config  is  the  line  starting with
  34. 'pronet-device:':   The number behind it is used for the transfer routines.
  35. One Amiga must have number 0, the other one must have number 1.  If this is
  36. not  the  case,  the  device will never return from the opening function or
  37. won't be opened at all.
  38.  
  39. pronet.device/OpenDevice                             pronet.device/OpenDevice
  40.  
  41.     NAME
  42.     OpenDevice -- a request to open a ProNET port
  43.  
  44.     SYNOPSIS
  45.     error = OpenDevice("pronet.device", unit, PNRequest, flags )
  46.     d0            a0               d0    a1         d1
  47.  
  48.     FUNCTION
  49.     Some components of the PNRequest structure must be filled in before
  50.     calling OpenDevice:
  51.  
  52.     pnr_MsgPort        Pointer to a Message Port where incoming
  53.                 data is sent to.
  54.  
  55.     pnr_NetSourcePort    Put your port number here. 0 is reserved
  56.                 for the pronet-handler/-server stuff.
  57.  
  58.     These two values MUST remain until closing the device.
  59.     
  60.     -1  in  pnr_NetSourcePort  has  a special meaning:  The port number
  61.     will  be  taken  from  the ProNET.config file.  pnr_Data1 must then
  62.     point  to  the title string introducing the line.  The first number
  63.     in  the  data  string will then be used as the port number.  If the
  64.     configuration    file   is   incomplete,  the  device  will  return
  65.     PNDERR_BADCONFIG !
  66.     -2  in  pnr_NetSourcePort  also has a  special meaning:  The device
  67.     takes the next free portnumber.
  68.     The new portnumber will then be put in pnr_NetSourcePort.
  69.  
  70.     INPUTS
  71.     "pronet.device" a pointer to the name of the device to be opened.
  72.             May be another device as well as long as it emulates
  73.             the original !!
  74.     unit         unused and should be set to 0 !!
  75.     PNRequest    a pointer to a PNRequest block
  76.     flags        unused and should be set to 0 !!
  77.  
  78.     RESULTS
  79.     error        0 --> opening OK.
  80.             PNDERR_BADCONFIG - see descr. of pnr_NetSourcePort
  81.             PNDERR_PORTEXISTS - port number is already allocated
  82.  
  83. pronet.device/CMD_WRITE                               pronet.device/CMD_WRITE
  84.  
  85.     NAME
  86.     CMD_WRITE -- send data to the other Amiga
  87.     (also PND_WRITE)
  88.  
  89.     FUNCTION
  90.     Sends the data specified in the PNRequest structure as soon as
  91.     possible to other machine.
  92.     The data consists of the second chunk appended to the first one.
  93.     Both chunks added must NOT be longer than $4000 / 16K bytes !!
  94.  
  95.     If the destination port doesn't exist on the remote machine, it
  96.     will be buffered there until the port is opened. The data will
  97.     be then sent in the order it was sent off.
  98.  
  99.     IO REQUEST
  100.     io_Command    CMD_WRITE / PND_WRITE
  101.     pnr_NetDestPort    Destination port number
  102.     pnr_Data1    Pointer to first chunk
  103.     pnr_Length1    Length of first chunk
  104.     pnr_Data2    Pointer to second chunk
  105.     pnr_Length2    Length of second chunk
  106.  
  107.     If you just want to transfer one chunk, set pnr_Length2 to zero.
  108.  
  109.     RESULTS
  110.     io_Error    always zero.
  111.  
  112.     BUGS
  113.     Until now, the machine is freezed while sending. (Bug?)
  114.  
  115.     NOTE
  116.     I-M-P-O-R-T-A-N-T:
  117.     Maximum length is 16K !!
  118.  
  119.     Both lengths are rounded up to word boundaries.
  120.  
  121.     Besides that, the contents of the PNRequest will not be changed !
  122.  
  123.     SEE ALSO
  124.  
  125. pronet.device/ReceivedData                         pronet.device/ReceivedData
  126.  
  127. Received  Data  will  be  sent  to  the Message Port you specified when you
  128. opened 'pronet.device'.  The data part starts behind the Message structure.
  129. It first contains the source port as one word, then the real data. Besides
  130. that, MN_LENGTH contains the length of the data including the source port
  131. word, and the first word of the LN_NAME pointer contains the destination
  132. port number (which shouldn't be of any use at all..)
  133.  
  134. After evaluation of the message, it should be replied.
  135.  
  136. pronet.device/GetConfigString                   pronet.device/GetConfigString
  137.  
  138.    NAME
  139.     GetConfigString -- get string out of DEVS:ProNET.config
  140.  
  141.    SYNOPSIS
  142.     configstr = GetConfigString(titlestring);
  143.     D0                           A0
  144.  
  145.     APTR GetConfigString(char *);
  146.  
  147.    FUNCTION
  148.     Returns the data string corresponding to the title string.
  149.     Must be released by FreeConfigString().
  150.  
  151.    INPUTS
  152.     titlestring    Pointer to null-terminated string. Usually ending
  153.             with a colon (':').
  154.  
  155.    RESULT
  156.     configstr    Pointer to null-terminated string.
  157.  
  158.    SEE ALSO
  159.     FreeConfigString()
  160.  
  161. pronet.device/FreeConfigString                 pronet.device/FreeConfigString
  162.  
  163.    NAME
  164.     FreeConfigString -- free string got by GetConfigString()
  165.  
  166.    SYNOPSIS
  167.     FreeConfigString(configstring);
  168.               A0
  169.  
  170.     FreeConfigString(char *);
  171.  
  172.    FUNCTION
  173.     Frees memory used by the string got by GetConfigString().
  174.  
  175.    INPUTS
  176.     configstring    Pointer to string got by GetConfigString().
  177.  
  178.    SEE ALSO
  179.     GetConfigString()
  180.  
  181.